Late last year, I spent some time disentangling aptitude's internal UI library and packaging it as a separate library, which I named cwidget. This article is the first in what will hopefully become a series describing the basic concepts and APIs of cwidget. It applies to the versions of cwidget currently available in Debian sid and lenny, 0.5.11-1 and 0.5.12-1. Autogenerated documentation of cwidget can be found here (but beware that as of this writing it is somewhat incomplete).

---

In this tutorial, I will walk through a simple program (hello.cc) that initializes cwidget, displays a simple message box, and then terminates the program when the user confirms the message. I assume a basic familiarity with C++. The first thing to do is to include the portions of cwidget that our program will use. Most importantly, we need the top level cwidget routines. These are the global routines that initialize cwidget, shut it down, and control its main loop (among other things).

#include <cwidget/toplevel.h>

cwidget comes with a collection of stock dialog boxes for things like displaying messages to the user. To access the routines that build these dialogs, we write:

#include <cwidget/dialogs.h>

All the symbols provided by the cwidget library are in the cwidget namespace. Using the full library name means that there's a reasonable chance that its names will not conflict with the names provided by other libraries; however, it's a real pain to type cwidget over and over. Since this is the only namespaced library we are using in this program, it's handy to define cw as an alias for cwidget:

namespace cw = cwidget;

Now we're ready to write the main routine. The first interaction of client code with the cwidget library is to initialize it. This will initialize the ncurses library and put the terminal into a mode suitable for a full-screen curses program.

cw::toplevel::init();

Next, we create a dialog box that will be displayed to the user. There are two things to note about this code:

1. cwidget is Unicode-aware and the ok() routine expects the message string to be a wide-character string. In this case, that means that we need to pass in a wide-character string (indicated by typing L in front of the string).
2. The second argument tells cwidget what to do when the ok button is pressed. The expression

     sigc::ptr_fun(cw::toplevel::exitmain);
   

   creates a slot using libsigc++. Briefly, a slot is a reference to a function or to a method of a class instance. When invoked, this particular slot will call cwidget::toplevel::exitmain(), which causes the main cwidget loop to exit. The slot is wrapped in cwidget::util::arg, a utility function that handles passing slots as optional arguments.

cw::widgets::widget_ref dialog =
    cw::dialogs::ok(L"Hello, world!",
                    cw::util::arg(sigc::ptr_fun(cw::toplevel::exitmain)));

Now that we have a widget, the next step is to arrange for it to appear on the terminal. In cwidget, control of the terminal is assigned to a single top-level widget: whatever it displays is what gets displayed on the terminal, and all user input is passed directly to it. In a real program this widget will typically manage a collection of sub-widgets and assign each one a screen region, but for now let's just display the dialog box we created:

cw::toplevel::settoplevel(dialog);

With everything initialized, we're ready to start the main loop. mainloop() will keep the display up-to-date and dispatch incoming events (for instance, keystrokes and mouse presses) until exitmain() is invoked.

cw::toplevel::mainloop();

When the user presses Enter or clicks on the Ok button in the dialog, exitmain() will be invoked by the binding that we set up earlier. Once this happens, we need to shut down cwidget in order to restore the terminal to its original state. If you skip this step, the terminal will be garbled and will not work properly when your program exits.

cw::toplevel::shutdown();

And that's it! To compile the program, change to the directory containing hello.cc and run:

$ g++ -o hello hello.cc $(pkg-config --cflags --libs cwidget)

Of course, you'll need to have the g++ and libcwidget-dev packages installed for this to work!

Sometimes people propose other solutions to have the Aptitude-gtk project done, like :

I d have thought that the most interesting way of doing aptitude-gtk would be to write a gtk backend for libcwidget. -Karellen

As this might be of interest to more people, I’ll repost Daniel Burrows‘ response :

Although I can see where you re coming from, a GTK+ backend to cwidget would have no significant upsides and significant downsides. The main upside to doing that from a practical point of view is that you would have only one piece of driver code for the GTK+ and curses interfaces. You wouldn t have to rewrite the entire interface from scratch to create a GUI frontend. But this is just an illusory benefit. cwidget is a terminal interface library and aptitude s curses frontend is a terminal-based UI. From a practical point of view, this means that aptitude regularly assumes that, for instance, to clear out a line it s sufficient to output $WIDTH space characters (ASCII 32) with the desired background style. A port of cwidget to GTK+ would have to introduce new, interface-independent abstractions for all operations like this and eliminate all direct use of terminal-based assumptions, at a significant cost in complexity for both cwidget and the aptitude frontend. In order to transition to these new conventions, I believe you would have to rewrite large portions of both cwidget *and* aptitude in order to make the interface abstraction layer work. (remember: the justification for doing this is to avoid having to rewrite aptitude!) Furthermore, while this approach avoids reimplementing aptitude s curses interface (sort of, except where it doesn t see above), it does so at the cost of requiring you to reimplement all of cwidget, for GTK+. I just did a quick line count (with wc -l ): in all of cwidget there are 23,390 lines of code, while aptitude s curses frontend has around 23,359 lines of code (some of which are actually shared with the other frontends but are in the curses directory due to the historical organization of the code tree). Not only is a rewrite of cwidget more involved, but the amount of code you d have to replace is comparable to the amount implicated in a rewrite of aptitude itself! Finally, even if these costs weren t enough to eliminate the idea, it s not at all clear to me that a GTK+ backend for cwidget is even desirable. Although aptitude has some superficial similarities to a GUI program, the process of designing an interface to run in a terminal (where the available input mechanisms are relatively restricted and all output is to a character-cell grid) is rather different from the process of designing a GUI. GUI programs can t rely on some simplifying assumptions that terminal programs can, and at the same time they have a lot more options available to them (just to name a few: graphics, multiple windows, differing text sizes and rotated text). Trying to force everything through an abstraction designed for terminal output would require you to either

1. eschew those options,
2. provide abstract GUI components that somehow fell back to terminal rendering in a terminal, or
3. add ways for the frontend to extend the abstract widgets with custom functionality.

1. is not an option because I (and, I think, Arthur) want to design a good GTK+ package manager, not a good GTK+ imitation of a console package manager. 2. and 3. amount, in my strong opinion, to writing two separate interfaces but intertwining their implementations in a mass of maintenance-resistant and extension-resistant spaghetti code. At the end of the day, I think that having two separate frontends (sharing backend logic where appropriate, of course) is a far cleaner and more maintainable design, and also easier to create.

As I said earlier, I intend to go a little farther than just making a GTK+ “skin” over the curses interface. Think less like gvim and emacs and more like maybe ddd. I should also add that the cwidget library is used by no major programs except Aptitude so few others would benefit from a GTK+ backend. As the cwidget library homepage says:

cwidget was originally an internal user interface library for the aptitude package manager. This means, on the one hand, that cwidget is known to work in the real world for a real application; on the other hand, it means that the feature set of cwidget is coextensive with the requirements of aptitude.

So I've been inexcusably tardy in announcing this, but Obey Arthur Liu is working on aptitude for Google's Summer of Code program. His goal is to write a third interface to the program, using GTK+ to produce the UI; as the abstract for his project states:

I will create a GTK+ GUI for Aptitude that will work alongside improved current ncurses and command-line interfaces. This will offer an alternative to Synaptic with an interface design geared toward usability and advanced functionality.

I'm looking forward to seeing what he comes up with! I think there are a lot of interesting possibilities in the design space of GUI package managers; hopefully he'll have time to explore at least a few of them. At the moment he's focusing on figuring out the care and feeding of the apt library backend and learning some of the quirks you have to deal with when writing a frontend against it. Arthur's blog can be found at http://www.milliways.fr and on Planet Debian. The Mercurial repository for his work can currently be found at http://dev.graffit.net/aptitude/hg/.

I've released version 0.4.11.4 of the aptitude package manager (release notes). The main motivation for this release is bug #483920, which would cause the resolver to choose solutions badly (e.g., it might prefer downgrading a bunch of packages to keeping them at their current versions). It also includes a simple fix for bug #136874, the fact that the output of aptitude search is badly suited for scripts (it still is, but now there's a command-line option that will make it better).

Dear Daniel, It looks like you are referring to my post, though you got my name wrong so that wasn’t immediately obvious. Of course this is far worse than the 2003 compromise in terms of the direct, known and quantifiable impact it has on our users. I don’t think I stated otherwise, so I hardly see why your post starts with “I disagree”.

Daniel, there have never, ever, been any changes in ikiwiki can could result in GUID changes on upgrade, with the exception of enabling usedirs, which is something you have to do manually. And there never will be any if I have anything to say about it.. Of course, you can cause the GUIDs of posts to change by renaming or moving the files around, or by changing the url to your blog. Doesn't explain why it happened of course.. PS, can I git clone your blog from somewhere? There's an interesting blip in your RecentChanges page that I'd like to figure out, where one time the change author is listed as "Daniel Burrows Daniel_Burrows".